﻿<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<title>IupProgressDlg</title>
<link rel="stylesheet" type="text/css" href="../../style.css">
<style type="text/css">
.style1 {
	border-width: 0;
}
</style>
</head>
<body>
<div id="navigation">
  <ul>
    <li><a href="#Creation">Creation</a></li>
    <li><a href="#Attributes">Attributes</a></li>
    <li><a href="#Callbacks">Callbacks</a></li>
    <li><a href="#Notes">Notes</a></li>
    <li><a href="#Examples">Examples</a></li>
    <li><a href="#SeeAlso">See Also</a></li>
  </ul>
</div>

<h2>IupProgressDlg<font size="4"> (since 3.9)</font></h2>
<p>Creates a progress dialog element. It is a predefined dialog for 
  displaying the progress of an operation. The dialog is meant to be shown with 
the show functions <strong>IupShow</strong> or <strong>IupShowXY</strong>.</p>
<h3><a name="Creation">Creation</a></h3>
<pre>Ihandle* IupProgressDlg(void); [in C]
iup.progressdlg{} -&gt; (<strong>elem</strong>: ihandle) [in Lua]
progressdlg() [in LED]</pre>
<p><u>Returns:</u> the identifier of the 
  created element, or NULL if an error occurs.</p>

<h3><a name="Attributes">Attributes</a></h3>
<p>Supports all the <a href="iupdialog.html#Attributes">IupDialog</a> attributes. 
But some attributes where changed to configure the dialog. We recommend changing 
only the following attributes:</p>
<p><a href="../attrib/iup_icon.html">ICON</a>: Dialog’s icon.</p>
<p>
<a href="../attrib/iup_title.html" style="font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">
TITLE</a><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255); display: inline !important; float: none;"><span class="Apple-converted-space">&nbsp;</span>(</span><font size="3" style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">non 
inheritable</font><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255); display: inline !important; float: none;">): 
Dialog’s title.<span class="Apple-converted-space">&nbsp;Default: NULL. If not set 
the title bar will not be displayed and the dialog will occupy less space on 
screen.</span></span></p>
<p>
<a href="../attrib/iup_visible.html" style="font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">
VISIBLE</a><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255); display: inline !important; float: none;">: 
Simply call<span class="Apple-converted-space">&nbsp;</span></span><b style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; letter-spacing: normal; line-height: 20px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">IupShow</b><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255); display: inline !important; float: none;"><span class="Apple-converted-space">&nbsp;</span>or<span class="Apple-converted-space">&nbsp;</span></span><b style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; letter-spacing: normal; line-height: 20px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255);">IupHide</b><span style="color: rgb(0, 0, 0); font-family: tahoma, verdana, arial, helvetica, geneva, sans-serif; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: 20px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255); display: inline !important; float: none;"><span class="Apple-converted-space">&nbsp;</span>for 
the dialog.</span></p>
<p><a href="../attrib/iup_parentdialog.html">PARENTDIALOG</a>
  (creation only): Name of a dialog to be used as parent. This dialog will 
  be always in front of the parent dialog. </p>
<p><a href="../attrib/iup_title.html">TITLE</a>:
  Dialog title.</p>
<p>Other attributes were set to values different than the default value (but can 
still be changed):</p>
<p><strong>RESIZE</strong>=NO, <strong>MAXBOX</strong>=NO, <strong>MINBOX</strong>=NO,
<strong>MENUBOX</strong>=NO</p>
<hr>
<p>New attributes. All non inheritable.</p>
<p><strong>COUNT</strong>: current count of iterations.</p>
<p><strong>INC</strong> (write-only): increment the current count by the given 
amount. If set to NULL will increment +1.</p>
<p><strong>PERCENT</strong>: current percent of iterations.</p>
<p><strong>TOTALCOUNT</strong>: total number of iterations. </p>
<p><strong>STATE</strong>: describe the state of the iteration. Can be: IDLE, 
PROCESSING, UNDEFINED or ABORTED. Default is IDLE. When INC, COUNT or PERCENT 
are set the state is changed to PROCESSING. If the user pressed the Cancel 
button the state is changed to ABORTED, but check the CANCEL_CB callback for 
other options. If the state is set to UNDEFINED by the application the progress 
bar will display an undefined state animation (same as setting MARQUEE=Yes in
<a href="../elem/iupprogressbar.html">IupProgressBar</a>), to resume processing 
set the state attribute to PROCESSING.</p>
<p><strong>DESCRIPTION</strong>: text description to be shown at the dialog.</p>
<p><strong>PROGRESSHEIGHT</strong>: height in pixels of the progress bar. 
Default: 30 (since 3.21)</p>
<p><strong>MINCLOCK</strong>: minimum time between counts to an actual screen 
update in milliseconds. So if each count increment is too fast this avoids 
updating the screen too often. Must at least has passed the minimum time for a 
screen update. Default: 250 (since 3.21)</p>
<p><strong>MINPERCENT</strong>: minimum percent between counts to an actual 
screen update, when the minimum clock has not reached yet. So if each count increment is too fast, but the application would like to update the screen anyway 
after the percent of the total progress has passed this minimum value. So at 
least some screen updates will occur. Default: 10 (since 3.21)</p>
<h3><a name="Callbacks">Callbacks</a></h3>
<p>Supports all the <a href="iupdialog.html#Callbacks">IupDialog</a> callbacks.</p>


<hr>


<p>New callbacks.</p>
<p><strong>CANCEL_CB</strong>:
  Action generated when the user clicked on the Cancel button.</p>

  
    
<pre>int function(Ihandle*<strong> ih</strong>); [in C]<br><strong>elem</strong>:cancel_cb() -&gt; (<strong>ret</strong>: number) [in Lua]</pre>

    
<p class="info"><strong>ih</strong>:
  identifier of the element that activated the 
  event.</p>

<p class="info"><u>Returns</u>: if different from IUP_CONTINUE then STATE will 
be changed to ABORTED, same behavior as if the callback does not exist. The 
returned value will also be returned in the "Cancel" button callback (since 
3.21).</p>

  
<h3><a name="Notes">Notes</a></h3>
<p>The <b>IupProgressDlg</b> will display the iteration state using a
<a href="../elem/iupprogressbar.html">IupProgressBar</a> control.</p>
<p>The dialog is <strong>not</strong> automatically closed, the application must 
do that manually inside the CANCEL_CB callback or inside your processing loop by 
checking the STATE attribute. </p>
<h3><a name="Examples">Examples</a></h3>
<pre>static int cancel_cb(Ihandle* ih)
{
  int ret = IupAlarm("Warning!", "Interrupt Processing?", "Yes", "No", NULL);
  if (ret == 1) /* Yes Interrupt */
  {
    IupExitLoop();
    return IUP_DEFAULT;
  }
  
  return IUP_CONTINUE;
}

...
Ihandle* dlg = IupProgressDlg();
  
IupSetAttribute(dlg, "TITLE", "IupProgressDlg Test");
IupSetAttribute(dlg, "DESCRIPTION", "Description first line\nSecond Line"); // Actually can have any number of lines.
IupSetCallback(dlg, "CANCEL_CB", cancel_cb);
IupSetAttribute(dlg, "TOTALCOUNT", "300");
  
IupShowXY(dlg, IUP_CENTER, IUP_CENTER);
...

// Called from inside the application processing loop
static int update_progress(Ihandle* ih)
{
  IupSetAttribute(ih, "INC", NULL);
  
  // This is just an example, the application can control the loop in other ways
  if (IupGetInt(ih, "COUNT")==IupGetInt(ih, "TOTALCOUNT"))
  {
    IupHide(ih);
    return 0;
  }
    
  return 1;
}
</pre>
<div align="center">
  <center>
  <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" id="AutoNumber1">
    <tr>
      <td  align="center" class="style1"><img border="0" src="images/progressdlg.png"></td>
    </tr>
  </table>
  </center>
</div>
<h3><a name="SeeAlso">See Also</a></h3>
<p>
<a href="../elem/iupprogressbar.html">IupProgressBar</a>,
<a href="iupdialog.html">IupDialog</a></p>

</body>

</html>